package com.aleyn.annotation

/**
 * @author : Aleyn
 * @date : 2023/07/23 : 14:32
 * @desc: 路由拦截器注解。
 *
 * 此注解用于标记一个实现了 `com.aleyn.router.core.RouterInterceptor` 接口的类，
 * 表明它是一个路由拦截器。LRouter 会在编译期收集所有被此注解标记的类，
 * 并在路由跳转过程中按照指定的优先级顺序依次执行它们。
 *
 * 拦截器是实现 AOP（面向切面编程）思想的关键，常用于处理通用逻辑，例如：
 * - 登录状态校验
 * - 用户权限检查
 * - 路由活动降级
 * - 跳转前的数据预处理或日志记录
 *
 * 工作原理：
 * 1. 编译期间，KSP 扫描并收集所有 `@Interceptor` 注解的类。
 * 2. 处理器将这些拦截器类的信息（包括优先级）生成到路由映射表中。
 * 3. 运行时，当发起路由跳转时，LRouter 会从映射表中取出所有拦截器，
 *    并根据 `priority` 组成一个拦截器链（Chain）。
 * 4. 路由请求会依次通过这个链条，每个拦截器都可以对请求进行处理、中断或放行。
 *
 * 使用示例：
 * ```kotlin
 * // 定义一个登录拦截器，优先级为 10
 * @Interceptor(priority = 10)
 * class LoginInterceptor : RouterInterceptor {
 *     override fun intercept(chain: RouterInterceptor.Chain) {
 *         val postcard = chain.request()
 *         // 如果目标页面需要登录，且用户未登录，则中断跳转并导航到登录页
 *         if (postcard.extra == RouteExtra.NEED_LOGIN && !UserManager.isLoggedIn()) {
 *             LRouter.getInstance().build("/account/login").navigation(postcard.context)
 *             chain.onInterrupt(RuntimeException("需要登录")) // 中断
 *         } else {
 *             chain.proceed(postcard) // 放行
 *         }
 *     }
 * }
 * ```
 *
 * @param priority 拦截器的优先级。数值越大，优先级越高，执行顺序越靠前。
 *                 默认值为 0。可以为负数。
 */
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.CLASS)
annotation class Interceptor(val priority: Byte = 0)
